home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / include / dev / pdev.h.jun2 < prev    next >
Text File  |  1989-05-31  |  12KB  |  314 lines
  1. /*
  2.  * pdev.h --
  3.  *
  4.  *    Declarations of the kernel/user-level-server interface for
  5.  *    pseudo-devices. A pseudo-device is a file
  6.  *    whose semantics are implemented by a user-level server process.
  7.  *    All other processes act on the file normally.  Their operations
  8.  *    on the file are mapped by the kernel into a request-response
  9.  *    exchange with the server process.  The types and constants defined
  10.  *    here are needed by the server programs to implement their
  11.  *    half of the pseudo-device protocol.  As well as implement the
  12.  *    regular file operations, Fs_Read, Fs_Write, and Fs_IOControl,
  13.  *    the server is involved in open/close time actions, and the
  14.  *    server helps control the select state of the pseudo device.
  15.  *    
  16.  *    A more complete explaination of pseudo-devices should be in
  17.  *    the man page (/sprite/doc/ref/devices/pdev), but the following
  18.  *    brief explaination may help.  The interface between the kernel
  19.  *    and the server process is based on filesystem streams.  The
  20.  *    server gets a "control stream" when it opens the pseudo-device
  21.  *    file with the FS_MASTER flag.  This control stream is readable
  22.  *    when a new client process has opened the pseudo-device.  The
  23.  *    control stream contains a short message with a new filesystem
  24.  *    streamID for a "service stream" that the server uses to communicate
  25.  *    with the new client.
  26.  *    Service streams are used by the server to get request messages
  27.  *    (that correspond to client operations) and return results.
  28.  *
  29.  *    Associated with each service stream is a "request buffer".  The server
  30.  *    gets request messages from clients indirectly; the requests are
  31.  *    placed into the request buffer, along with their data, and the server
  32.  *    learns about new requests by reading messages from the service stream
  33.  *    that contain 'firstByte' and 'lastByte' offsets into the request buffer.
  34.  *    This buffered interface lets the kernel stack up many requests (writes,
  35.  *    in particular) before a    context switch is required to the server
  36.  *    program.  Of course, this also lets the server handle all the queued
  37.  *    requests at one time.  When the    server has handled requests it updates
  38.  *    the 'firstByte' pointer by making a IOC_PDEV_SET_PTRS ioctl() on
  39.  *    the service stream.
  40.  *
  41.  *    There can also be a read ahead buffer associated with each service
  42.  *    stream.  This is filled with data by the server program that is to
  43.  *    be read by a client, and the kernel moves data from this buffer,
  44.  *    which is again in the server's address space, to the client without
  45.  *    having to switch out to the server process. 
  46.  *    
  47.  * Copyright 1987 Regents of the University of California
  48.  * All rights reserved.
  49.  * Permission to use, copy, modify, and distribute this
  50.  * software and its documentation for any purpose and without
  51.  * fee is hereby granted, provided that the above copyright
  52.  * notice appear in all copies.  The University of California
  53.  * makes no representations about the suitability of this
  54.  * software for any purpose.  It is provided "as is" without
  55.  * express or implied warranty.
  56.  *
  57.  *
  58.  * $Header: /sprite/src/lib/include/dev/RCS/pdev.h,v 1.13 89/01/27 09:33:56 brent Exp $ SPRITE (Berkeley)
  59.  */
  60.  
  61. #ifndef _PDEV
  62. #define _PDEV
  63.  
  64. #include "proc.h"
  65. #include "fs.h"
  66.  
  67. /*
  68.  * Pseudo-device operations
  69.  *    PDEV_OPEN        The first request after a client open.
  70.  *    PDEV_DUP        OBSOLETE, but might resurrect itself.
  71.  *    PDEV_CLOSE        The last request.
  72.  *    PDEV_READ        Read data from the pseudo-device.
  73.  *    PDEV_WRITE        Write data to the pseudo-device.
  74.  *    PDEV_IOCTL        Special operation on the pseudo-device.
  75.  *    PDEV_WRITE_ASYNC    Asynchronous write.  No reply needed.
  76.  *
  77.  * These two only apply to pseudo-device connections to pseudo-file-systems.
  78.  * For regular pseudo-devices the kernel takes care of attribute handling.
  79.  *    PDEV_GET_ATTR        Get attributes given a pdev connection.
  80.  *    PDEV_SET_ATTR        Set attributes given a pdev connection.
  81.  */
  82.  
  83. typedef int Pdev_Op;
  84.  
  85. #define PDEV_OPEN        1
  86. /* #define PDEV_DUP        2 */
  87. #define PDEV_CLOSE        3
  88. #define PDEV_READ        4
  89. #define PDEV_WRITE        5
  90. #define PDEV_IOCTL        6
  91. #define PDEV_WRITE_ASYNC    7
  92. #define PDEV_GET_ATTR        8
  93. #define PDEV_SET_ATTR        9
  94.  
  95. /*
  96.  * A pseudo-device server gets a 'control stream' when opening a pseudo-device.
  97.  * The following structure describes the messages read from the control stream.
  98.  * Control stream messages are used to notify the server that it
  99.  * has a new private stream because a client opened the pseudo-device.
  100.  */
  101. typedef struct Pdev_Notify {
  102.     unsigned int    magic;            /* == PDEV_NOTIFY_MAGIC */
  103.     int            newStreamID;
  104.     int            reserved;        /* Extra */
  105. } Pdev_Notify;
  106.  
  107. #define PDEV_NOTIFY_MAGIC    0x1D4E4F54
  108.  
  109. /*
  110.  * The first message on a private stream is a PDEV_OPEN.
  111.  * This message identifies the client process, its host, and the host's
  112.  * byte order to the server.
  113.  */
  114.  
  115. typedef struct Pdev_OpenParam {
  116.     int flags;            /* Flags from the Fs_Open call */
  117.     Proc_PID pid;        /* Client's process ID */
  118.     int hostID;            /* Host ID where client is from */
  119.     int uid;            /* User ID of the client process */
  120.     int byteOrder;        /* Byte order identifier */
  121.     int reserved;        /* Extra */
  122. } Pdev_OpenParam;
  123.  
  124. /*
  125.  * PDEV_READ, PDEV_WRITE request parameters. 
  126.  *    There is a reply block for read, the data.  There is no
  127.  *    reply data for a write.
  128.  */
  129.  
  130. typedef struct {
  131.     int        offset;        /* Byte offset for the transfer, the length of
  132.                  * the transfer is implied by the sizes in the
  133.                  * Request header. */
  134.     unsigned int familyID;    /* Can be used to enforce controlling tty */
  135.     Proc_PID    procID;        /* Needed for signalling, etc. */
  136.     int        reserved;    /* Extra */
  137. } Pdev_RWParam;
  138.  
  139. /*
  140.  * PDEV_IOCTL request parameter.
  141.  */
  142.  
  143. typedef struct {
  144.     int        command;    /* I/O control command #. */
  145.     unsigned int familyID;    /* Can be used to enforce controlling tty */
  146.     Proc_PID    procID;        /* Process id of calling process */
  147.     int        byteOrder;    /* Defines caller's byte order.  Needed
  148.                  * to correctly interpret following data. */
  149.     int        reserved;    /* Extra */
  150. } Pdev_IOCParam;
  151.  
  152. /*
  153.  * PDEV_SET_ATTR request parameters.  These are in the Pdev_Request header,
  154.  * and the new Fs_Attributes record is passed as the data block following
  155.  * the header.
  156.  */
  157.  
  158. typedef struct {
  159.     int        flags;        /* Which attributes to set */
  160.     int        uid;        /* User ID */
  161.     int        gid;        /* Group ID */
  162. } Pdev_SetAttrParam;
  163.  
  164.  
  165. /*
  166.  * When a client does something to the pseudo-device the server gets
  167.  * a corresponding request message.  The structure of it is defined here.
  168.  * The control information in the request header is the same for both
  169.  * pseudo-device and pseudo-filesystem operations.
  170.  */
  171.  
  172. typedef struct {
  173.     unsigned int magic;        /* PDEV_REQUEST_MAGIC or PFS_REQUEST_MAGIC */
  174.     Pdev_Op    operation;    /* What action is requested. */
  175.     int        messageSize;    /* The complete size of the request header
  176.                  * plus data, plus padding for alignment */
  177.     int        requestSize;    /* Size of data following this header */
  178.     int        replySize;    /* Max size of the reply data expected. */
  179.     int        dataOffset;    /* Offset of data from start of header */
  180. } Pdev_RequestHdr;
  181.  
  182. typedef struct {
  183.     Pdev_RequestHdr    hdr;    /* with PDEV_REQUEST_MAGIC */
  184.     union {            /* Additional parameters to the operation. */
  185.     Pdev_OpenParam        open;
  186.     Pdev_RWParam        read;
  187.     Pdev_RWParam        write;
  188.     Pdev_IOCParam        ioctl;
  189.     Pdev_SetAttrParam    setAttr;
  190.     } param;
  191. } Pdev_Request;
  192.  
  193. #define PDEV_REQUEST_MAGIC    0x7265717D
  194.  
  195. /*
  196.  * The server replies to each message on the private stream with
  197.  * a reply header followed with reply data (if any).  The status in
  198.  * the reply header will be the return value of the client's system call,
  199.  * except for FS_WOULD_BLOCK and FS_LOOKUP_REDIRECT which are processed
  200.  * by the kernel.
  201.  */
  202.  
  203. typedef struct Pdev_Reply {
  204.     unsigned int magic;        /* == PDEV_REPLY_MAGIC */
  205.     ReturnStatus status;    /* Return status of remote call */
  206.     int        selectBits;    /* Return select state bits */
  207.     int        replySize;    /* Size of the data in replyBuf, if any */
  208.     Address    replyBuf;    /* Server space address of reply data */
  209.     int        reserved;    /* Extra */
  210. } Pdev_Reply;
  211.  
  212. #define PDEV_REPLY_MAGIC    0x52455058
  213.  
  214. /*
  215.  * I/O Controls for server streams.
  216.  *    IOC_PDEV_READY        The server uses this to notify the kernel
  217.  *                that the pseudo-device is ready for I/O now.
  218.  *                The input buffer should contain an int
  219.  *                with an or'd combination of FS_READABLE,
  220.  *                FS_WRITABLE, or FS_EXCEPTION.
  221.  *    IOC_PDEV_SET_BUF    These are used to tell the kernel where the
  222.  *                request buffer and read ahead buffer (if any)
  223.  *                are. The input buffer should contain a
  224.  *                Pdev_SetBufArgs struct.  Note that this
  225.  *                needs to be done after getting a notification
  226.  *                on the control stream before any request
  227.  *                (i.e. the client's open request) comes through.
  228.  *                This can also be done later to change the
  229.  *                buffer if needed.  The buffer change takes
  230.  *                place as soon as the previous one empties.
  231.  *                The switch is indicated by the requestAddr
  232.  *                that you read from the service stream.
  233.  *    IOC_PDEV_WRITE_BEHIND    Set (Unset) write-behind buffering in the
  234.  *                request buffer.  The single input argument
  235.  *                is a pointer to a Boolean; TRUE enables
  236.  *                write-behind, FALSE inhibits it.  The default
  237.  *                is no write-behind.
  238.  *    IOC_PDEV_SET_PTRS    These are used to update the firstByte and
  239.  *                lastByte pointers into the request and
  240.  *                read ahead buffers.  The input buffer
  241.  *                is a Pdev_BufPtrs structure.
  242.  *    IOC_PDEV_REPLY        This is used to send a reply to a request.
  243.  *                The input buffer contains a Pdev_Reply.  This
  244.  *                includes an address (in the server's space)
  245.  *                of a buffer containing reply data, if any.
  246.  *    IOC_PDEV_BIG_WRITES    Set (Unset) the ability of the client to
  247.  *                write a chunk larger than will fit into
  248.  *                the request buffer.  This is to support
  249.  *                UDP socket semantics that prevent a client
  250.  *                from writing more than the declared packet size.
  251.  *                (Of course, we could do better by keeping the
  252.  *                 existing semantics that automatically break
  253.  *                 the write into smaller ones...)
  254.  *                The input buffer should reference a Boolean;
  255.  *                TRUE enables big writes (which is the default)
  256.  *                FALSE prevents big writes.
  257.  *    IOC_PDEV_SIGNAL_OWNER    This sends a signal to the controlling process
  258.  *                of the pseudo-device.  If there is no owner
  259.  *                then this is ignored.  The input buffer contains
  260.  *                the signal number and code to send.
  261.  *
  262.  */
  263.  
  264. #define IOC_PDEV        (2 << 16)
  265. #define IOC_PDEV_READY        (IOC_PDEV | 0x1)
  266. #define IOC_PDEV_SET_BUF    (IOC_PDEV | 0x2)
  267. #define IOC_PDEV_WRITE_BEHIND    (IOC_PDEV | 0x3)
  268. #define IOC_PDEV_SET_PTRS    (IOC_PDEV | 0x4)
  269. #define IOC_PDEV_REPLY        (IOC_PDEV | 0x5)
  270. #define IOC_PDEV_BIG_WRITES    (IOC_PDEV | 0x6)
  271. #define IOC_PDEV_SIGNAL_OWNER    (IOC_PDEV | 0x7)
  272.  
  273. /*
  274.  * Input structure for the IOC_PDEV_SET_BUF IOControl
  275.  */
  276.  
  277. typedef struct Pdev_SetBufArgs {
  278.     Address    requestBufAddr;        /* Server's address of request buffer */
  279.     int        requestBufSize;        /* Num bytes in the request buffer */
  280.     Address    readBufAddr;        /* NULL if no read ahead.  Non-NULL
  281.                      * implicitly enables read-ahead. */
  282.     int        readBufSize;        /* Num bytes in the read ahead buffer */
  283. } Pdev_SetBufArgs;
  284.  
  285. /*
  286.  * Input structure for IOC_PDEV_SET_PTRS IOControl.
  287.  */
  288.  
  289. typedef struct Pdev_BufPtrs {
  290.     int magic;            /* == PDEV_BUF_PTR_MAGIC */
  291.     Address    requestAddr;    /* The address of the request buffer.  This is
  292.                  * valid when reading only, and it indicates
  293.                  * what request buffer is being used.  See
  294.                  * IOC_PDEV_SET_BUF. */
  295.     int requestFirstByte;    /* Byte offset of the first valid data byte
  296.                  * in the request buffer.  If -1 buf is empty */
  297.     int requestLastByte;    /* Byte offset of the last valid data byte. */
  298.     int readFirstByte;        /* Byte offset of the first valid data byte
  299.                  * in the read ahead buffer. -1 => empty */
  300.     int readLastByte;        /* Byte offset of the last data byte. */
  301. } Pdev_BufPtrs;
  302.  
  303. #define PDEV_BUF_PTR_MAGIC    0x3C46DF14
  304.  
  305. /*
  306.  * Stucture for the IOC_PDEV_SIGNAL_OWNER operation.
  307.  */
  308. typedef struct Pdev_Signal {
  309.     unsigned int signal;
  310.     unsigned int code;
  311. } Pdev_Signal;
  312.  
  313. #endif _PDEV
  314.